Skip to content

feat(credits): add an opt-in gateway credits ledger - #74

Merged
ALikesToCode merged 3 commits into
feat/scim-provisioningfrom
feat/credits-ledger
Oct 9, 2026
Merged

ALikesToCode merged 3 commits into
feat/scim-provisioningfrom
feat/credits-ledger

Conversation

@ALikesToCode

Copy link
Copy Markdown
Owner

Summary

Adds an opt-in, append-only credits ledger kept separate from usage estimates. With CREDITS_ENABLED unset or off (the default), /v1/credits and /admin/credits/* return 404 and nothing else changes.

  • Settings:
    • CREDITS_ENABLED. Empty means off; a malformed value is off with one warning.
    • CREDITS_CURRENCY defaults to USD, the only accepted value.
  • Ledger:
    • Integer micro-USD only, within ±10^15. Floats and booleans are rejected.
    • Entries are credit, reserve, commit, release, adjust and compensate, each idempotent by operation ID per owner. The same ID with different content returns 409 credits_conflict.
    • Every write is a compare-and-swap on the owner's balance revision. Corrections append compensation entries, and history is never rewritten.
  • Enforcement:
    • Reservations and negative adjustments may not make available credit negative (409 credits_insufficient).
    • A commit always records the actual cost and closes its hold, even past the hold. Available credit can then go negative, and new reservations are refused until credits cover it.
    • An unknown cost keeps the hold. An unpriced reservation under enforcement is denied, never charged zero.
  • Owner read: GET /v1/credits (models scope) returns balance, held, available and cursor-paged entries, with Cache-Control: no-store.
  • Administrator adjustment: POST /admin/credits/adjust needs an administrator session, CSRF and If-Match (428 when missing, 412 when stale). It takes {owner, amount_microusd, operation_id, reason}, writes an audit row and never grants anything automatically.
  • Authority: the ledger implements the enterprise CreditAuthority (reserve/commit/reconcile). Callers pass the owner's current revision; on 412 they re-read it and retry with the same operation ID.

Details are in docs/credits-ledger.md.

Wiring

All new files; no existing file changes. Standalone Flask uses SQLite, and D1 deployments use the private credits domain in worker/credits-d1.mjs. The Wave 7 integration adds:

  • mounting register_credits_routes;
  • the private endpoint and its dispatcher entry;
  • connecting the authority to reservation, settlement and reconciliation.

Until then, enabling credits only serves the owner read and administrator adjustment routes.

Review fix

The first version applied the no-negative rule to commits too. A request whose actual cost exceeded its hold plus the available balance then failed to commit: the cost was never recorded and the hold never closed. Commits now always record, as described above. Shared Python and Worker vectors cover the overrun and the recovery.

Shared registrations

  • tests/test_credits_ledger_worker.mjs in test:worker.
  • worker/credits-d1.mjs in the edge module inventory, and the three credit routes in the Flask route inventory.
  • CREDITS_ENABLED and CREDITS_CURRENCY in the Container env keys.
  • credits_balances, credits_entries and credits_audit in REQUIRED_D1_TABLES.

Stacked on #73

Migration numbers must be contiguous in each PR, so this branch merges feat/scim-provisioning (#73, migration 0036), which stacks on #72, #71 and #70. Merge those first. Payment billing stacks on this one.

Tests

  • tests/test_credits_ledger.py and tests/test_credits_ledger_worker.mjs cover:
    • integer bounds and overflow;
    • duplicate operations applied exactly once;
    • concurrent reservations;
    • unknown-cost holds;
    • per-attempt charges;
    • linked corrections without rewrites;
    • owner isolation;
    • commit overruns and recovery;
    • the default off state.
  • Full Python suite: 4,942 passed, 2 skipped. ruff, mypy and bandit are clean.
  • npm run test:worker: 1,840 passed. npm run test:integration: 7 passed.
  • cf:migrations:check reports 37 contiguous, additive migrations. test:deploy, free routes, client headers and the wrangler deploy --dry-run bundle all pass.
  • tests/test_frontend_build.mjs fails locally because @tailwindcss/cli is not installed. It fails the same way on main.

Apply the migration before enabling the flag: npx wrangler d1 migrations apply multillm-intelligence --remote.

CI notes

  • GitHub python/node jobs: the dependency-audit steps fail on every branch, including main. fix(deps): clear the CI dependency audit advisories #42 fixes that.
  • Workers Builds: fails on this stack because the Wave 3 base adds the AdmissionCoordinator Durable Object migration, which wrangler versions upload cannot apply. This is expected until wrangler deploy runs on main.

This is part of Wave 7. The README line comes with the Wave 7 integration PR.

CREDITS_ENABLED (off by default) keeps an append-only integer micro-USD ledger
per owner: credit, reserve, commit, release, adjust and compensate entries,
each idempotent by operation ID and written with a compare-and-swap on the
owner's balance revision. Corrections append compensation entries and never
rewrite history.

Reservations and negative adjustments may not make available credit
negative. A commit always records the actual cost and closes its hold, so an
overrun leaves available credit negative and new reservations are refused
until credits cover it. An unknown cost keeps the hold.

GET /v1/credits returns the owner's balance and paged entries, and
POST /admin/credits/adjust needs an administrator session and If-Match. The
ledger implements the enterprise CreditAuthority; connecting it to request
reservations comes with integration (migration 0037).
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Updated (UTC)
❌ Deployment failed
View logs
multillm-proxy 3a2a109 Oct 09 2026, 08:00 AM

@coderabbitai

coderabbitai Bot commented Oct 9, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 728a76cd-8c4c-4f88-a2da-a8e2afde2229

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@ALikesToCode
ALikesToCode merged commit 7441b03 into feat/scim-provisioning Oct 9, 2026
4 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant